#-*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

__all__ = ['IDataConverterHandler']

from traits.api import HasTraits

class IDataConverterHandler(HasTraits):

  def convertData(self, fmt_in, fmt_out, input_data, input_mode,
                    output_mode, output_path=None):
    """
    Input modes :
      - strlist
      - stream
      - path
      - data
      - python

    Output modes :
      - stream
      - path
      - data
      - iterator

    All examples use these kind of data :
    
    dataformat: dataconverter.format.ini
    
    .. code-block ::
      
      [group1]
      key1 = 3
    
    dataformat: dataconverter.format.rst
    
    .. code-block ::
    
      Option Summary
      ==============

      group1
      ------
        - **key1** =  3
    
    datarepr: dataconverter.repr.configparser

    DataRepr based on ConfigParser

    .. code-block :: python

      data = handler.createData('dataconverter.repr.configparser')
      data.add_section('group1')
      data.set('group1', 'key1', '3')


    Input modes :
    
    **strlist**
    
    if text format: list of **unicode** strings.
    if binary format: list of **str** strings.
    
    Usefull to create data directly in text editor or python script. 

    .. code-block :: python
    
      lines = [u'[group1]', u'key1 = 3']

      # or from file (but input_mode='path' is prefered in this case)

      import codecs
      f = codecs.open('config.ini','r','utf-8')
      lines = f.readlines()
      f.close()

      handler.convert(fmt_in='dataconverter.format.configparser', 
                      fmt_out='dataconverter.format.rst', 
                      input_data=lines, input_mode='text'
                      output_mode='path', output_path=u'config.rst')

    **stream**
    A stream (ex: open file or StringIO)

    if text format, stream must contains **unicode** strings
    (ex: file open with codecs module)

    Usefull to create data directly in text editor or python script. 

    .. code-block :: python
    
      lines = [u'[group1]', u'key1 = 3']

      from StringIO import StringIO
      stream = StringIO()
      stream.writelines(lines)
      stream.pos = 0

      # or using to_stream method :
      stream = to_stream(lines)

      # or from file (but input_mode='path' is prefered in this case)
      import codecs
      stream = codecs.open('config.ini','r','utf-8')


      handler.convert(fmt_in='dataconverter.format.configparser', 
                      fmt_out='dataconverter.format.rst', 
                      input_data=stream, input_mode='stream'
                      output_mode='path', output_path=u'config.rst')

      stream.close()

    **data**
    a valid IDataRepr implementation object.
    parameter "fmt_in" is useless in this case and is not read.
      
    .. code-block :: python
    
      data = handler.createData('dataconverter.repr.configparser')
      data.add_section('group1')
      data.set('group1', 'key1', '3')

      handler.convert(fmt_in=None,fmt_out='dataconverter.format.rst', 
                      input_data=data, input_mode='data'
                      output_mode='path', output_path=u'config.rst')

    **python**
    a valid python code generating a data object.
    parameter "fmt_in" is useless in this case and is not read.
      
    .. code-block :: python
    
      pycode = [
        u"data = handler.createData('dataconverter.repr.configparser')",
        u"data.add_section('group1')",
        u"data.set('group1', 'key1', '3')"
      ]
      pystr = u'\n'.join(pycode)

      handler.convert(fmt_in=None,fmt_out='dataconverter.format.rst', 
                      input_data=pystr, input_mode='python'
                      output_mode='path', output_path=u'config.rst')


    **path**

    .. code-block :: python
    
      handler.convert(fmt_in='dataconverter.format.configparser',
                      fmt_out='dataconverter.format.rst', 
                      input_data=Path(u'config.ini'), input_mode='path'
                      output_mode='path', output_path=u'config.rst')

    :param fmt_in: Input IDataFormat implementation or IDataFormat identifier (str)
    :param fmt_out: Output IDataFormat implementation or IDataFormat identifier (str)
    :param input_data: Input data, may be stream, string, IDataFormat implementation or Path depending on input_mode
    :param input_mode: Specify input data type. Available modes: 'python', 'path', 'text', 'data'
    
    :return: generated object. May be a Path, IDataFormat or Stream dependings on output_mode 
    """

  def convert(self, fmt_in, fmt_out, input_data, input_mode,
                    output_mode, output_path=None):
    """
    recordable version of convertData
    """

  def createData(self, datarepr_id):
    """
    create a new datarepr from datarepr_id
    """
